🔐 API de UsuarioPermissaoTipoMensagem - Documentação Completa

📋 Visão Geral

A API de UsuarioPermissaoTipoMensagem é responsável por toda a gestão de permissões de usuários para tipos de mensagem no sistema CordenaAi, incluindo controle granular de quais tipos de mensagem cada usuário pode receber, adição, remoção e verificação de permissões. Esta API fornece a base para o sistema de comunicação personalizado, permitindo que administradores controlem o fluxo de mensagens por usuário e tipo.

🎯 Endpoints Disponíveis

🔐 UsuarioPermissaoTipoMensagem - Gestão de Permissões de Tipos de Mensagem

1. GET /api/UsuarioPermissaoTipoMensagem/usuario/{usuarioId}

Obter Permissões por Usuário

• Descrição: Retorna todas as permissões de tipos de mensagem de um usuário específico
• Método: GET
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros:
  • usuarioId (path): ID único do usuário
• Resposta: Array de objetos PermissaoTipoMensagemResponse
• Uso: Interface do usuário para visualizar suas permissões, dashboard administrativo

2. GET /api/UsuarioPermissaoTipoMensagem/todas

Obter Todas as Permissões

• Descrição: Retorna todas as permissões do sistema (acesso administrativo)
• Método: GET
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros: Nenhum
• Resposta: Array de objetos PermissaoTipoMensagemResponse
• Uso: Dashboard administrativo, relatórios de permissões, auditoria

3. POST /api/UsuarioPermissaoTipoMensagem

Adicionar Nova Permissão

• Descrição: Adiciona uma nova permissão de tipo de mensagem para um usuário
• Método: POST
• Autenticação: Requerida (JWT Bearer Token)
• Body: Objeto AdicionarPermissaoRequest
• Resposta: Objeto PermissaoTipoMensagemResponse criado
• Uso: Formulários de configuração de permissões, setup inicial de usuários

4. DELETE /api/UsuarioPermissaoTipoMensagem

Remover Permissão

• Descrição: Remove uma permissão específica de um usuário (soft delete)
• Método: DELETE
• Autenticação: Requerida (JWT Bearer Token)
• Body: Objeto RemoverPermissaoRequest
• Resposta: Confirmação de remoção
• Uso: Interface administrativa para revogar permissões

5. GET /api/UsuarioPermissaoTipoMensagem/verificar/{usuarioId}/{tipoMensagemId}

Verificar Permissão Específica

• Descrição: Verifica se um usuário tem permissão para receber um tipo específico de mensagem
• Método: GET
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros:
  • usuarioId (path): ID único do usuário
  • tipoMensagemId (path): ID do tipo de mensagem
• Resposta: Objeto com status da permissão
• Uso: Validação antes do envio de mensagens, sistema de notificações

🔧 Modelo de Dados

Estrutura da Permissão

{
  "id": "int",
  "usuarioId": "string",
  "nomeUsuario": "string",
  "userName": "string",
  "tipoMensagemId": "int",
  "nomeTipoMensagem": "string",
  "ativo": "boolean",
  "criacao": "datetime",
  "atualizacao": "datetime",
  "historicoPermissao": "string",
  "opcoes": "string"
}

DTOs de Requisição

AdicionarPermissaoRequest

{
  "usuarioId": "string",
  "tipoMensagemId": "int",
  "historicoPermissao": "string",
  "opcoes": "string"
}

RemoverPermissaoRequest

{
  "usuarioId": "string",
  "tipoMensagemId": "int"
}

Tipos de Mensagem Disponíveis

🔐 Autenticação e Autorização

Todos os endpoints requerem:

• JWT Bearer Token no header Authorization
• Permissões específicas baseadas no tipo de usuário:
  • Administradores: Acesso completo a todos os endpoints
  • Coordenadores: Acesso para gerenciar permissões de suas turmas
  • Usuários normais: Acesso limitado às próprias permissões

📊 Casos de Uso Principais

1. Configuração Inicial de Permissões

POST /api/UsuarioPermissaoTipoMensagem
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioId": "user-123",
  "tipoMensagemId": 2,
  "historicoPermissao": "Permissão inicial para mensagens urgentes",
  "opcoes": "{\"prioridade\": \"alta\"}"
}

2. Verificação de Permissão Antes do Envio

GET /api/UsuarioPermissaoTipoMensagem/verificar/user-123/2
Authorization: Bearer {token}

3. Consulta de Permissões do Usuário

GET /api/UsuarioPermissaoTipoMensagem/usuario/user-123
Authorization: Bearer {token}

4. Remoção de Permissão

DELETE /api/UsuarioPermissaoTipoMensagem
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioId": "user-123",
  "tipoMensagemId": 5
}

5. Auditoria de Permissões (Admin)

GET /api/UsuarioPermissaoTipoMensagem/todas
Authorization: Bearer {token}

⚠️ Validações e Regras de Negócio

Validações Obrigatórias

• UsuarioId: Obrigatório, deve existir no sistema
• TipoMensagemId: Obrigatório, deve ser um tipo válido
• Permissão única: Não é possível duplicar permissões para o mesmo usuário e tipo

Regras de Negócio

• Soft Delete: Permissões são desativadas, não removidas permanentemente
• Reativação: Permissões existentes podem ser reativadas
• Auditoria: Todas as operações são logadas com timestamps
• Múltiplas permissões: Usuário pode ter permissão para 1, 2, 3 ou todos os tipos
• Herança: Permissões podem ser herdadas de grupos ou roles
• Validação de envio: Sistema verifica permissões antes de enviar mensagens

🚨 Tratamento de Erros

Códigos de Status HTTP

• 200: Sucesso
• 201: Permissão criada com sucesso
• 400: Dados inválidos ou permissão já existe
• 401: Não autorizado
• 403: Acesso negado
• 404: Usuário ou tipo de mensagem não encontrado
• 409: Conflito (permissão já existe)
• 500: Erro interno do servidor

Formato de Erro

{
  "error": "string",
  "message": "string",
  "details": "string",
  "timestamp": "datetime"
}

📈 Performance e Limitações

Limitações

• Paginação: Listas retornam máximo 100 registros por página
• Rate Limiting: 500 requests por hora por usuário
• Timeout: 15 segundos por requisição
• Cache: Dados de permissões são cacheados por 2 minutos

Otimizações

• Índices: Busca otimizada por UsuarioId e TipoMensagemId
• Cache: Permissões ativas são cacheadas em memória
• Compressão: Respostas comprimidas com gzip
• Batch operations: Suporte para operações em lote

🔄 Integração com Outros Módulos

Módulos Relacionados

• Sistema de Mensagens: Validação de permissões antes do envio
• Usuários: Associação com dados do usuário
• Tipos de Mensagem: Referência aos tipos disponíveis
• Auditoria: Log de todas as alterações de permissões
• Notificações: Controle de quais notificações o usuário pode receber

📱 Uso em Aplicações

Web App

• Dashboard administrativo de permissões
• Configuração de permissões por usuário
• Relatórios de permissões e auditoria
• Interface de verificação de permissões

Mobile App

• Visualização de permissões do usuário
• Configuração de preferências de notificação
• Verificação de permissões em tempo real

Sistema de Mensagens

• Validação automática antes do envio
• Filtragem de destinatários por permissões
• Log de tentativas de envio sem permissão

🛠️ Manutenção e Monitoramento

Logs Importantes

• Criação de novas permissões
• Remoção/desativação de permissões
• Tentativas de acesso sem permissão
• Erros de validação de permissões

Métricas Monitoradas

• Número de permissões por usuário
• Taxa de sucesso das operações
• Tempo de resposta dos endpoints
• Uso de cache de permissões

📚 Exemplos Práticos

Fluxo Completo de Configuração de Permissões

1. Verificação de usuário existente
2. POST /api/UsuarioPermissaoTipoMensagem com dados da permissão
3. Validação de dados e regras de negócio
4. Criação da permissão no banco de dados
5. Atualização do cache de permissões
6. Log da operação para auditoria

Fluxo de Verificação de Permissão

1. GET /api/UsuarioPermissaoTipoMensagem/verificar/{usuarioId}/{tipoMensagemId}
2. Consulta no cache ou banco de dados
3. Validação do status ativo da permissão
4. Retorno do resultado da verificação
5. Log da consulta para monitoramento

Fluxo de Remoção de Permissão

1. DELETE /api/UsuarioPermissaoTipoMensagem com dados da permissão
2. Verificação da existência da permissão
3. Soft delete (marcação como inativa)
4. Atualização do cache de permissões
5. Log da operação para auditoria

🔧 Configurações Avançadas

Opções JSON

O campo opcoes permite configurações personalizadas:

{
  "prioridade": "alta",
  "horariosPermitidos": ["08:00-18:00"],
  "canaisPreferidos": ["push", "email"],
  "silenciarFinaisDeSemana": true
}

Histórico de Permissões

O campo historicoPermissao mantém o histórico de alterações:

• “Permissão inicial concedida pelo admin”
• “Permissão reativada após solicitação do usuário”
• “Permissão removida por violação de políticas”

Versão: 1.0
Última Atualização: Outubro de 2025
Responsável: Equipe de Desenvolvimento CordenaAi